feat(key_mgr): Add Key Manager HAL for ESP32-C5 and ESP32-P4 (IDFGH-17725) by hrushikesh430 · Pull Request #113 · espressif/esp-stub-lib

hrushikesh430 · 2026-05-27T09:45:55Z

What

Adds a Key Manager (KM) hardware abstraction layer (HAL) for ESP32-C5 and ESP32-P4. This HAL is what the esp-flasher-stub keymanager plugin calls to deploy and recover keys through the chip's Key Manager and HUK Generator peripherals.

Why

esptool is gaining Key Manager support (host side + a flasher-stub plugin). The plugin needs a thin, chip-specific driver to actually drive the KM peripheral. This PR provides that driver for C5 and P4. There is no crypto on the chip — the host (espsecure) does all AES/ECDH preprocessing, and the stub only drives the peripheral state machine.

What's in this PR

target/key_mgr.h — the plugin↔HAL contract. Declares HUK generator control, KM bring-up, state-machine stepping, key-memory I/O, and result checks (HUK/key valid, eFuse KM_INIT_KEY presence). API names mirror ESP-IDF's esp_key_mgr.c so it can be reviewed side by side; IDF's locks/logging/RTOS plumbing are dropped (the stub is single-threaded).
ESP32-C5 driver (esp32c5/src/key_mgr.c + SoC register headers) — clock/reset bring-up, key-memory MMIO helpers, 5-bit eFuse key-purpose decoding, HUK status/configure, external ECC bring-up for ECDH0/ECDH1.
ESP32-P4 driver (esp32p4/src/key_mgr.c + SoC register headers) — the same HAL mapped onto P4's HP_SYS_CLKRST clock/reset layout and 4-bit eFuse key-purpose fields.

HUK_INFO is 660 bytes to match IDF's HUK_INFO_LEN.

Testing

Testing report -
KM_TESTING_REPORT.md

Notes

Companion PR in esp-flasher-stub adds the keymanager plugin and bumps its submodule to this commit.
Draft — not yet ready for review.

Add a Key Manager (KM) hardware abstraction layer that the esp-flasher-stub keymanager plugin uses to deploy and recover keys through the KM and HUK Generator peripherals. What's included: - target/key_mgr.h: the plugin<->HAL contract. Declares HUK generator control, KM bring-up, state-machine stepping, key-memory I/O, and result checks (HUK/key valid, eFuse KM_INIT_KEY presence). API names mirror ESP-IDF's esp_key_mgr.c so the code can be reviewed side by side; the IDF locks, logging and RTOS plumbing are dropped (the stub is single-threaded). - ESP32-C5 driver + SoC register headers: clock/reset bring-up, key-memory MMIO helpers, 5-bit eFuse key-purpose decoding, HUK status/configure, and external ECC bring-up for ECDH0/ECDH1. - ESP32-P4 driver + SoC register headers: the same HAL mapped onto P4's HP_SYS_CLKRST clock/reset layout and 4-bit eFuse key-purpose fields. HUK_INFO is 660 bytes to match IDF's HUK_INFO_LEN. There is no chip-side crypto: the host (espsecure) does all AES/ECDH preprocessing and the stub only drives the peripheral.

Dzarda7 · 2026-05-27T10:22:55Z

Hello @hrushikesh430, I know this is not ready and even now it is quite good, just a heads up for you, please try to follow the contribution guide.

Copilot

Pull request overview

Adds a Key Manager (KM) + HUK Generator target HAL for ESP32-C5 and ESP32-P4 within esp-stub-lib, providing the chip-side peripheral driving needed by an external flasher-stub “keymanager” plugin.

Changes:

Introduces a new internal target HAL contract header (target/key_mgr.h) for KM/HUK operations.
Adds ESP32-C5 and ESP32-P4 KM/HUK implementations plus minimal SoC register definitions for each.
Wires the new sources into the ESP32-C5 and ESP32-P4 target builds via CMake.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
src/target/base/include/target/key_mgr.h	New internal plugin↔HAL interface for KM/HUK operations and constants/enums.
src/target/esp32c5/src/key_mgr.c	ESP32-C5 KM/HUK driver (bring-up, state machine ops, MMIO helpers, efuse purpose scan).
src/target/esp32c5/include/soc/keymng_reg.h	ESP32-C5 Key Manager register definitions (plus PCR/ECC-related bring-up regs).
src/target/esp32c5/include/soc/huk_reg.h	ESP32-C5 HUK Generator register definitions (including LP_AON/PUF SRAM controls).
src/target/esp32c5/CMakeLists.txt	Adds `src/key_mgr.c` to the ESP32-C5 target library.
src/target/esp32p4/src/key_mgr.c	ESP32-P4 KM/HUK driver using HP_SYS_CLKRST clock/reset sequencing and efuse purpose scan.
src/target/esp32p4/include/soc/keymng_reg.h	ESP32-P4 Key Manager register definitions (hw_ver3).
src/target/esp32p4/include/soc/huk_reg.h	ESP32-P4 HUK Generator register definitions (hw_ver3).
src/target/esp32p4/include/soc/hp_sys_clkrst_reg.h	Minimal HP_SYS_CLKRST register subset needed for KM/ECC/ECDSA clock/reset.
src/target/esp32p4/CMakeLists.txt	Adds `src/key_mgr.c` to the ESP32-P4 target library.

hrushikesh430 · 2026-05-27T11:43:02Z

contribution guide

Yes, sure. Thanks.

- New common/src/key_mgr.c with weak defaults for every stub_target_* declared in target/key_mgr.h. - SOC_KEY_MANAGER_SUPPORTED in c5+p4 soc_caps.h. - BIT(n) instead of 1U<<n; EFUSE register access via SOC header macros (new efuse_reg.h for C5; P4 uses its existing definitions). - stub_target_huk_configure returns STUB_LIB_OK / STUB_LIB_FAIL / STUB_LIB_ERR_INVALID_ARG (caller's err != 0 check stays compatible). - STUB_LOGE before every error return; NULL-buffer check at the top of every public MMIO I/O helper.

- Restrict ESP32-P4 Key Manager to v3.0+ (ROM ECO >= 5, 660-byte HUK); add stub_target_km_is_supported() reading the wafer major version from eFuse and reject earlier P4 silicon that used the 384-byte HUK. - Clamp Key Manager mem I/O lengths to the peripheral window size in the read/write wrappers (defensive bounds). - Use BIT(STUB_KM_KEY_TYPE_FLASH_XTS_AES) instead of a magic bit index. - Reconcile HUK 660/384 docstrings and clarify the 384-byte path is the MMIO window; tidy internal HAL wording and mem I/O preconditions.

…rt check The keymanager plugin calls stub_target_km_is_supported(), which lands in esp-stub-lib PR #113; the previously committed submodule pointer predates it and the plugin no longer compiled. Pin the submodule to the PR #113 head (espressif/esp-stub-lib#113) — to be re-bumped to the merged commit once that PR lands.

AdityaHPatwardhan

Two questions from reviewing the C5/P4 Key Manager HAL.

AdityaHPatwardhan · 2026-06-17T10:07:01Z

+
+void stub_target_km_wait_for_state(stub_km_state_t state)
+{
+    while (stub_target_km_get_state() != state) {


Should this wait have a timeout? With no watchdog in the stub, if KM never reaches the expected state the host just sees a hang with no error (same applies to the P4 wait_for_state).

AdityaHPatwardhan · 2026-06-17T10:07:01Z

+     * configure_huk asserts KEYMNG_HUK_VLD instead, but on this C5 v1.2
+     * board the KM doesn't latch HUK from a standalone huk_configure —
+     * it only sets KEYMNG_HUK_VLD as a side-effect of a subsequent
+     * key-deploy. Cross-boot RECOVER on a cold chip currently fails


Can we surface this known cross-boot RECOVER failure (gen=2/risk=7 on a cold C5) in the PR description before un-drafting? It's easy to miss buried in the comment here.

hrushikesh430 and others added 2 commits May 27, 2026 15:11

Apply automatic fixes from pre-commit hooks

7e65fa1

hrushikesh430 mentioned this pull request May 27, 2026

feat(keymanager): Add Key Manager flasher-stub plugin (ESP32-C5/P4) (ESPTOOL-1324) espressif/esp-flasher-stub#77

Draft

github-actions Bot changed the title ~~feat(key_mgr): Add Key Manager HAL for ESP32-C5 and ESP32-P4~~ feat(key_mgr): Add Key Manager HAL for ESP32-C5 and ESP32-P4 (IDFGH-17725) May 27, 2026

espressif-bot added the Status: Opened Issue is new label May 27, 2026

erhankur requested a review from Copilot May 27, 2026 10:54

Copilot started reviewing on behalf of erhankur May 27, 2026 10:54 View session

Copilot AI reviewed May 27, 2026

View reviewed changes

hrushikesh430 and others added 4 commits June 2, 2026 16:07

Apply automatic fixes from pre-commit hooks

58d95c1

Apply automatic fixes from pre-commit hooks

4ae32cb

espressif-bot assigned hrushikesh430 Jun 9, 2026

AdityaHPatwardhan reviewed Jun 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(key_mgr): Add Key Manager HAL for ESP32-C5 and ESP32-P4 (IDFGH-17725) - #113

feat(key_mgr): Add Key Manager HAL for ESP32-C5 and ESP32-P4 (IDFGH-17725)#113
hrushikesh430 wants to merge 6 commits into
espressif:masterfrom
hrushikesh430:feat/keymanager-approach-3

hrushikesh430 commented May 27, 2026 •

edited

Loading

Uh oh!

Dzarda7 commented May 27, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hrushikesh430 commented May 27, 2026

Uh oh!

AdityaHPatwardhan left a comment

Uh oh!

AdityaHPatwardhan Jun 17, 2026

Uh oh!

AdityaHPatwardhan Jun 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

hrushikesh430 commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

What's in this PR

Testing

Notes

Uh oh!

Dzarda7 commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hrushikesh430 commented May 27, 2026

Uh oh!

AdityaHPatwardhan left a comment

Choose a reason for hiding this comment

Uh oh!

AdityaHPatwardhan Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

AdityaHPatwardhan Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

hrushikesh430 commented May 27, 2026 •

edited

Loading

Dzarda7 commented May 27, 2026 •

edited

Loading